##########################################################################
Physics 2D Extensions
##########################################################################

Thank you for purchasing Physics 2D Extensions! This asset contains a set of add-ons for Unity's 2D physics engine and requires Unity 4.3 or above to function correctly.

==========================================================================
Installation
==========================================================================

Importing the Package:

	Before installing Physics 2D Extensions, make sure that there are no compiler errors in your project. Extract the package into your assets folder - make sure to include all files.

Installing Physics 2D Extensions:

	Once the package has been extracted, a window will appear. Follow the instructions in the install window to complete the installation. If you accidentially close the window or do not see an installation window, please go to Window > Physics 2D Extensions > Install Physics 2D Extensions.

Registration:

	You can optionally register your copy of Physics 2D Extensions. This ensures full product support - you can also sign up for an email notification whenever a new update is released.
	
	You can register at: 
		https://thinksquirrel.com/product-registration
		
	See the "Product Support" section below for more information.

Uninstalling Physics 2D Extensions:

	Physics 2D Extensions should always be uninstalled prior to upgrading. To uninstall, remove the following folders:

	C# Installation

		Assets/Physics 2D Extensions
	
	JavaScript installation

		Assets/Physics 2D Extensions
		Assets/Plugins/Physics 2D Extensions

==========================================================================
Getting Started
==========================================================================

There are a number of new components that can be added. You can find all of them under Component > Physics 2D > Extra Joints, Component > Physics 2D > Controllers, and Component > Physics 2D > Other.

Joints work like Unity's physics joints - they provide a constraint of motion between two rigidbodies. These components should be placed on one of the two rigidbodies they affect. Joints can also be fixed to the world by not providing a second body. This is different from Unity's 2D physics implementation (which sets the world anchor to 0,0) and more similar to Unity's 3D physics implementation (which sets the world anchor to the joint's current position).

Controllers apply a set of constraints to an entire group of rigidbodies, and only affect a certain area. Controllers can be added to objects with or without rigidbodies. They are used to represent forces like wind and buoyancy.

The controller filter is a component that allows more fine-grained control over whether a body will be affected by a controller. This component requires a Rigidbody2D to be present. For more information, check out the "Controller Filter" topic.

Finally, a drag control component is included, for dragging rigidbodies around with mouse or touch input.

An example scene can be found in the "Assets/Physics 2D Extensions/P2D Example Project/Unity##" folder.

==========================================================================
Component Reference - Joints
==========================================================================

All Joints - These properties are shared with all joints.
	
	Connected Body
		The other Rigidbody2D object that the one with the joint is connected to. If this is null then the other end of the joint will be fixed at a point in space.
----

----
Rope Joint - Connects two rigidbodies with an enforced maximum distance.Works better than a distance or hinge joint for connecting together ropes that won't stretch improperly.
	
	Anchor
		Coordinate in local space where the end point of the joint is attached.
	Connected Anchor
		Coordinate in the other object's local space where its end of the joint is attached.
----

----
Weld Joint - Connects two rigidbodies with a weld between them. This joint is only stable with objects that are close together, and provides an easy way to "stick" one object to another.

	(no additional properties)
----

----
Wheel Joint - Provides both rotation and suspension needed to produce a physically accurate wheel in 2D space.

	Use Motor
		Should the wheel motor be enabled?
	Motor Speed
		Target motor speed (degrees/sec).
	Maximum Motor Force
		The maximum torque the motor can apply while attempting to reach the target speed.
	Anchor
		Coordinate in local space where the end point of the joint is attached.
	Suspension Axis
		Controls the axis of suspension from the wheel to the connected body.
	Frequency
		The frequency at which the suspension spring oscillates while the rigidbodies are approaching the desired separation distance (cycles per sec).
	Damping Ratio
		The degree to which spring oscillation is suppressed.

==========================================================================
Component Reference - Controllers
==========================================================================

All Controllers - These properties are shared with all controllers.

	Rigidbodies
		The list of rigidbodies that can be affected by this controller.
	Enabled on Layers
		A layer mask that controls which layers a controller will affect.
	Offset
		The local space position of the controller's influence area.
	Dimensions
		The local space size of the controller's influence area.
----

----
Buoyancy Controller - Provides buoyancy simulation, with the option to provide a direction of flow.

	Velocity
		The velocity of flow for the buoyancy controller. This can be used to simulate a liquid's flow.
	Density
		The density of the buoyancy area. This will affect how much and how strongly other objects float.
	Linear Drag Coefficient
		A multiplier applied to linear drag in the buoyancy equation. Higher values will slow down the linear movement of objects in the buoyancy area.
	Angular Drag Coefficient
		A multiplier added to the angular drag in the buoyancy equation. Higher values will slow down the angular movement of objects in the buoyancy area.
----

----
Gravity Controller - Provides n-body planetary gravity simulation. Note that, as in reality, a forever-stable orbit cannot exist in two dimensions through physics simulation alone.

	Gravity Type
		Controls how gravitational falloff is calculated. Can be either linear distance or based on the distance squared (the latter is more realistic).
	Strength
		A multiplier that controls the strength of gravitational forces.
	Min Radius
		The minimum radius from a body's position at which gravitational forces are present.
	Max Radius
		The maximum radius from a body's position at which gravitational forces are present.
	Points
		A set of points, or singularities that exert gravitational forces on objects. These points are not influenced by other rigidbodies or points.
----

----
Velocity Limit Controller - Limits the linear and angular velocity of  rigidbodies within its area.

	Limit Linear Velocity
		If true, linear velocity will be limited.
	Limit Angular Velocity
		If true, angular velocity will be limited.
	Max Linear Velocity
		The maximum linear velocity of affected rigidbodies.
	Max Angular Velocity
		The maximum angular velocity of affected rigidbodies.
----

----
Wind Controller - Provides a basic wind simulation, with support for curves.
	
	Wind Type
		Controls the type of wind force. This can be constant, or based on a curve.	
	Force Type
		Controls how the wind force is exterted on objects. Wind can emit from either a point, or along a direction.
	Position
		Controls the wind force's position, in local space.
	Direction
		Controls the wind force's direction, in local space. Point forces are not affected by this.
	Ignore Position
		If enabled, the wind force will ignore the body's position for directional force calculation. When disabled, objects "behind" the controller will not be affected by wind. Point forces are not affected by this.
	Strength
		The strength of the wind force.
	Strength Curve
		Controls how the wind force's strength changes over time. This only takes effect if the Wind Type is set to Curve.
	Decay Mode
		Controls how the wind force's strength decays over distance. This can be constant (None), instant (Step), linear, based on the inverse square distance, or based on a custom curve.
	Decay Curve
		Controls how the wind force's strength changes over distance. This only takes effect if the Wind Type is set to Curve.
	Decay Start
		All rigidbodies less than this distance will be affected by the full wind force.
	Decay End
		All rigidbodies greater than this distance will not be affected by the full wind force. 
	Divergence
		Controls the amount of directional turbulence. Can be a range from 0 to 1.
	Variation
		Controls the amount of strength variation.	
	Time Scale
		Determines the time scale of all curves. This is a quick way to slow down or speed up changes in the wind.

==========================================================================
Component Reference - Controller Filter
==========================================================================

Controller Filter - Allows for more fine-grained filtering of rigidbodies 
with different controllers. Controller filters are cached to prevent 
GetComponent lookups every frame.

Filtering order:
	
	* If the body is destroyed, it will not be affected by a controller
	* If the body's game object is not active, it will not be affected by a controller
	* If a controller filter component not present or not enabled:
		- The "Enabled On Layers" property is checked
	* If a controller filter is present:
		- The controller filter's flags are checked
		- If the controller is not ignored, the "Enabled On Layers" property is checked

Properties:

	Ignored controllers
		A set of flags representing the controllers that should ignore this rigidbody.

==========================================================================
Component Reference - Drag Control
==========================================================================

Drag Control - Provides an easy way to pick up and drag objects. Works with mouse, touch, or custom input events and can filter by layer.

Properties:
	
	Input Camera
		The camera to use to calculate input position. This defaults to the main camera.
	Use Mouse Events
		If true, listen to mouse events.
	Use Touch Events
		If true, listen to touch (and multitouch) events.
	Mouse Button
		The mouse button to use for picking up objects.
	Mouse Distance
		The margin of error (in pixels) to use when picking up objects with the mouse.
	Touch Distance
		The margin of error (in pixels) to use when picking up objects using touch.
	Max Force
		The maximum amount of force that can be exerted on the object while dragging.
	Enabled On Layers
		A layer mask that controls which layers can be dragged.

==========================================================================
API Reference
==========================================================================

The API is similar to Unity's API - All of the inspector variables are accessible as properties at runtime. There are a few additional methods, detailed below.

All API classes are in the following namespace(s):
	
	ThinksquirrelSoftware.Phys2D

Joints:

	void RecalculateMassData(bool addedOrRemovedColliders)
	     
		Recalculates the mass data for the rigidbodies connected to this joint.
	     
	    This method should be called if a collider on the rigidbody changes (different points, size, or radius), or if the mass of either rigidbody is modified. Please see the "Additional Notes" section below for more information.
	    
	    If set to true, indicate that colliders were added or removed to a rigidbody.

Controllers:

	Rigidbody[] GetRigidbodies()
	    
	    Returns the array of rigidbodies that this controller will affect.

	    Note that this method will allocate a new array, so it should not be called every frame. 

	void AddRigidbody(Rigidbody2D body)

		Adds a body to the controller's internal list, allowing it to be affected by the controller.

	bool RemoveRigidbody(Rigidbody2D body)

	    Removes a body from the controller's internal list. Returns false if the body cannot be successfully removed or was not found in the controller's list.

	[BuoyancyController2D] void RecalculateMassData(Rigidbody body)
		
		Recalculates the mass data for a rigidbody in the controller's rigidbody list. Please see the "Additional Notes" section below for more information.

	[BuoyancyController2D] void RecalculateMassDataAll()
		
		Recalculates the mass data for all rigidbodies in the controller's rigidbody list. Please see the "Additional Notes" section below for more information.

Controller Filter:

	void IgnoreControllerType(ControllerType controllerType)
	
		Ignores the controller type. All controllers of this type will no longer affect this rigidbody. An overload is provided that accepts a controller object as a parameter.
	
	void RestoreControllerType(ControllerType controllerType)
	
		Restores the controller type. All controllers of this type will now affect this rigidbody. An overload is provided that accepts a controller object as a parameter.
	
	bool IsControllerTypeIgnored(ControllerType controllerType)

		Returns true if this controller type is currently ignored. An overload is provided that accepts a controller object as a parameter.

Drag Control:

	void ResetEventData()
		
		Discards all current input data and resets everything to a default, unpressed state.
	
	OnCustomInput - custom input event:
		
		This event fires every physics frame to determine the state of any custom input devices, after mouse and touch input has been processed. Subscribe to this event in order to control dragging with a custom input device, such as a keyboard, controller, existing event system, etc.
		
	InputInfo - custom input struct:
		
		worldPosition - The world position of the input device.
		worldDistance - The maximum margin of error for the input device, in world space.
		state - The current state of the input device (Started, Dragging, or Ended).
		
	CustomInputDelegate - custom input delegate:
		
		arguments:
			DragControl2D - The DragControl2D component that called the custom input event.
		
		returns:
			InputInfo - A custom input struct describing the state of the input device.	

==========================================================================
Additional Notes
==========================================================================

Due to Unity's implementation of 2D physics, there are some important differences to how extended components work. These have been outlined below.

The following applies to all joints:

	There is currently no way to include the "Collide connected" toggle in current versions of Unity - all joints will collide by default. Using layer collision will work around the issue, until Unity provides a way to specify two rigidbodies that should not collide.

The following applies to all joints and the buoyancy controller:

	Unity currently does not provide a way to access either the moment of inertia or center of mass for 2D rigidbodies. Because of this, an additional calculation has to be performed once, on the first frame. This calculation is still in the sub-millisecond range for all but the most intensive applications, but needs to be redone if the number of colliders on a body, collider shapes, or body's mass are changed. Once Unity provides access to these variables, recalculation of mass data will not be necessary.

The following applies to all controllers:

	Controllers will only affect bodies with a Collider2D component attached, unless the controller's dimensions are set to (0, 0). Controllers have a limit of 256 Collider2D components (and up to 256 Rigidbody2D components) that can be affected at any given frame. This is for performance reasons.

==========================================================================
Product Support
==========================================================================

You can register your product for access to additional support, product update notifications and beta releases.

To register, please visit the following link:
https://thinksquirrel.com/product-registration

Also make sure to check out the Thinksquirrel support forum:
https://thinksquirrel.com/forum

==========================================================================
Aknowledgements
==========================================================================

Some bits of code were taken from the Box2D project, (the same physics engine used as a base for Unity's 2D physics system) and the Farseer Physics library (an open-source C# physics engine based on Box2D). You can find out more about Box2D and Farseer Physics here:

http://box2d.org/
http://farseerphysics.codeplex.com/